From 7a3073be12eefd11e25e3e9900c59551b156e481 Mon Sep 17 00:00:00 2001 From: parkrrrr Date: Wed, 15 Sep 2004 18:32:10 +0000 Subject: [PATCH] DOcumentation for stack filter; forgot to commit this yesterday. --- gpsbabel/README | 76 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/gpsbabel/README b/gpsbabel/README index 0d2a46d29..5daf2b4a9 100644 --- a/gpsbabel/README +++ b/gpsbabel/README @@ -810,6 +810,82 @@ DATA FILTERS to sort by geocaching.com waypoint ID's when the input comes from a GPX file that has GC numbers in it. + STACK + + This filter is designed to solve advanced problems that involve + shuffling multiple lists of waypoints. It has three distinct + sets of suboptions: + + PUSH + + Pushes the current list of waypoints onto the stack. If + the 'copy' suboption is specified, a copy of the current + list is pushed onto the stack; otherwise, the current + list is cleared. + -x stack,push + -x stack,push,copy + + POP + + 'Pops' the top list of waypoints off of the stack. What is + done with that list depends on the suboption specified. If + the 'append' suboption is specified, the top list of waypoints + from the stack is added to the end of the current list of + waypoints. If the 'discard' option is specified, the top + list of waypoints is removed from the stack and discarded, + leaving the current list of waypoints unchanged. If the + 'replace' option is specified, or if no option is specified, + the top list of waypoints from the stack replaces the current + list of waypoints; the previous contents of the current list + are discarded. + -x stack,pop + -x stack,pop,discard + -x stack,pop,append + + SWAP + + Swaps the current list of waypoints with a list from the + stack. If no further options are specified, the current + list is swapped with the top list on the stack. If the + 'depth' option is specified, it indicates which item on + the stack should be swapped. + -x stack,swap + -x stack,swap,depth=2 + + The stack can be used in conjunction with other filters to + implement a "union" or "logical or" functionality. The basic + idea is to use the stack to store copies of the original list + of waypoints, then use the 'swap' function to replace each copy + with a filtered list. Finally, append all of the filtered lists + to create one big list, which is then output. The following + example finds a list of all points that are either inside county A + or inside county B. Any points that are inside both counties are + duplicated (but the duplicates can be removed with the DUPLICATE + filter; see above.) + + gpsbabel -i gpx -f in.gpx \ + -x stack,push,copy \ + -x polygon,file=county_a.txt \ + -x stack,swap \ + -x polygon,file=county_b.txt \ + -x stack,pop,append \ + -o gpx -F out.gpx + + This example reads a large list of waypoints and extracts the + points within 20 miles of each of two cities, writing the + waypoint descriptions into two different PalmDoc files and + exporting all of the points to the GPS receiver: + + gpsbabel -i gpx -f indiana.gpx \ + -x stack,push,copy \ + -x radius,lat=41.0765,lon=-85.1365,distance=20m \ + -o palmdoc,dbname=Fort\ Wayne -F fortwayne.pdb \ + -x stack,swap \ + -x radius,lat=39.7733,lon=-86.1433,distance=20m \ + -o palmdoc,dbname=Indianapolis -F indianapolis.pdb \ + -x stack,pop,append \ + -o magellan -F fwaind.wpt + COMMON USAGE Invocation was meant to be flexible. Unfortunately, that can -- 2.30.2